feat(flags-core): add header-driven Vercel mode on the shared cache - #511

…tion

…ce response as recovery

Polling now starts only once the stream has given up for good (retries
exhausted, 401, or token failure); transient disconnects and startup
timeouts keep serving the cache while the stream reconnects. Stream and
polling freshness extend their fresh window by staleWhileRevalidate
before reads block. getDatafile() is a snapshot again and never starts a
source. Any successful source response renews cache age and clears the
failure deadline even when the version guard keeps the stored data, a
last-resort fetch clears failure too, and clear() resets the deadline so
reinitialization after shutdown starts clean and rewires source events.
A 401 on an empty cache no longer disables the client permanently.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WjWjQyvVvunuerU51GvB9M

…out polling

With a recorded failure the cache otherwise waits for the live source to
recover, but a stream-only client has no source left once the stream gives
up. Reads in that state now revalidate over HTTP, including after a failed
refresh.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WjWjQyvVvunuerU51GvB9M

…t getDatafile

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WjWjQyvVvunuerU51GvB9M

…s while degraded

The controller no longer tracks a separate streamExhausted flag: stream startup reports connected/connecting/failed and the state plus StreamSource.active carry the rest. Degraded now means no live source is active, and degraded reads apply stale-while-revalidate over HTTP on the configured source's schedule, treating unknown age as stale so data recovers once the stream stops for good. Polling gives up on a 401 and enters degraded, and a retried initialization after a failed first poll keeps the active polling source instead of leaving it in degraded.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

…staleIfError only

Degraded reads no longer borrow the stream or polling schedules. Data refreshed within staleWhileRevalidate is served as is, older data is served while a background refresh runs, and data older than staleWhileRevalidate plus staleIfError waits for the refresh. Unknown age refreshes in the background.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

…after suspension

While streaming, stale reads serve the cache and expired reads wait for the stream to confirm instead of starting an HTTP fetch that the next ping would cancel. StreamSource.revalidate() drops a connection silent beyond the fresh window (keeping a young replacement), and waits up to the fetch deadline for the next message; CacheReadPolicy.revalidate routes stale and expired reads through it. Polling, header mode and degraded reads keep refreshing over HTTP.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

…equest

Module-scope initialization still starts no network activity in Vercel mode. Inside a request, initialize() now prepares the cache the way the first evaluation would: a matching version header confirms it, a newer version or an empty cache fetches, and a missing entry starts streaming or polling. It rejects only when no definitions are available. Runtime setup happens once per lifecycle, so repeated calls in later requests only repeat the preparation. Lazy initialization from reads passes prepareRequest: false, because the read resolves the request itself and must keep accurate cache metrics.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Streaming data now stays stale until five minutes after the last message, or until the fresh window plus staleWhileRevalidate if that is longer. A runtime resuming from an ordinary suspension serves the cache while the ping watchdog reconnects in the background, instead of blocking the read on a stream reconnect. Reads only wait for the stream once the connection has been silent beyond that.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Streaming reads now always serve the cache, reporting data older than one missed ping as stale, and never start HTTP work while the stream is live. Recovery stays with the stream: the ping watchdog reconnects silent connections, including right after a suspended runtime resumes, and exhausted retries fall back to polling or HTTP revalidation. Production metrics showed rare ~2s (up to 10s) warm precompute() waits from the blocking path.

This removes the stream revalidation wait (StreamSource.revalidate, the per-connection reconnect handle and the cache's resolveThroughSource) and the five-minute streaming expiry, which only existed to bound that wait.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>